The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / pure_src / lib2.src < prev next >

Wrap

Text File | 1993-03-03 | 47.8 KB | 1,460 lines

screen( capsensitive("access")) NAME access - determine accessibility of a file SYNOPSIS #include <unistd.h> int access(const char *path, int amode); DESCRIPTION path points to a path naming a file. access checks the named file for accessibility, using the real user ID and real group ID of the process. The bit pattern contained in amode is constructed as follows: 04: read 02: write 01: execute (search for directories) 00: check existence of file The owner of a file has permission checked with respect to the "owner" read, write and execute mode bits. Members of the file's group other than the owner have permissions checked with respect to the "group" mode bits, and all others have permissions checked with respect to the "other" mode bits. If the real user ID is 0 (super-user), success is always returned for any existing file. SEE ALSO \#chmod\#, \#stat\# RETURN VALUES 0 if access is permitted. -1 if access is not permitted or if the file does not exist; errno is set to indicate the error. NOTE Under TOS or on a MS-DOS (TOS) file-system, this call is pretty bogus and can best be used to check for existence of the file.\end screen( capsensitive("alarm")) NAME alarm - set a process alarm clock SYNOPSIS #include <unistd.h> unsigned alarm(unsigned sec); DESCRIPTION alarm instructs the alarm clock of the calling process to send the signal SIGALRM to the calling process after the number of real time seconds specified by sec have elapsed. When 32-bit integers are used, the largest value that is allowed for sec is (2^31 - 1) / 1000; larger values are silently rounded down. Thus, the longest alarm takes about 3 weeks to deliver. Alarm requests are not stacked; successive calls reset the alarm clock of the calling process. If sec is 0, any previously made alarm request is cancelled. SEE ALSO \#pause\#, \#signal\#, \#sigpause\#, \#sigset\# \#Talarm\#; this system call is used in the implementation of this routine. RETURN VALUES alarm returns the amount of time previously remaining in the alarm clock of the calling process, or 0 if no alarm was scheduled. NOTE This call only works when MiNT is active; under TOS, zero is always returned.\end screen( capsensitive("atexit")) NAME atexit - register exit cleanup function SYNOPSIS #include <stdlib.h> int atexit(void (*)(void)); DESCRIPTION atexit registers exit cleanup functions to be called when the process is terminated using \#exit\#. The functions supplied should not need any parameters and should not return any values. Processes terminated by calling _exit will circumvent any registered cleanup functions. RETURN VALUES 0 on success. -1 on failure; errno is set to indicate the error. SEE ALSO \#exit\#, \#_exit\# NOTE ANSI requires atexit to be able to register at least 32 functions. The mintlibs allocate memory dynamically through using \#malloc\#; it is hoped this is okay.\end screen( capsensitive("chdir")) NAME chdir - change working directory SYNOPSIS #include <unistd.h> int chdir(const char *path); DESCRIPTION Path points to the path name of a directory. chdir causes the named directory to become the current working directory, the starting path for path searches for path names not beginning with /. SEE ALSO \#getcwd\# \#Dsetdrv\#, \#Dsetpath\# - these GEMDOS functions are used to implement this library function. RETURN VALUES 0 upon successfull completion. -1 when an error occurs; errno is set to indicate the error.\end screen( capsensitive("chmod")) NAME chmod - change mode of file SYNOPSIS #include <unistd.h> int chmod(const char *path, int mode); DESCRIPTION path points to a path name naming a file. chmod sets the access permission portion of the named file's mode according to the bit pattern contained in the mode parameter. The possible access permission bits are defined in the include file <sys/stat.h>, see the \#stat\# call. The effective user ID of the process must match the owner of the file or be super-user to change the mode of a file. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error. SEE ALSO \#chown\#, \#creat\#, \#fcntl\#, \#open\#, \#stat\#, \#umask\# \#Fchmod\#, \#Fattrib\#; these system calls are used in the implementation of this routine.\end screen( capsensitive("chown")) NAME chown - change owner and group of a file SYNOPSIS #include <unistd.h> int chown(const char *path, int uid, int gid); DESCRIPTION path points to a path naming a file. The owner ID and group ID of the file are set to the numeric values contained in uid and gid respectively. Only a process with effective uid 0 or whose effective uid matches the user ownership of the file may make this call. In the latter case, the new uid must match the old one, and the calling process must also be a member of the group specified by gid. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error SEE ALSO \#chmod\# \#Fchown\#; this system call is used in the implementation of this routine. NOTES When MiNT is not active, this routine is bogus. MS-DOS (TOS) file systems do not understand file ownership.\end screen( capsensitive("close")) NAME close - close a file descriptor SYNOPSIS #include <unistd.h> int close(int fildes); DESCRIPTION fildes is a file descriptor obtained from a \#creat\#, \#open\#, \#dup\#, \#fcntl\# or \#pipe\# system call. close closes the file descriptor indicated by fildes. All outstanding record locks owned by the process on the file indicated by fildes are closed. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error. SEE ALSO \#creat\#, \#dup\#, \#fcntl\#, \#open\#, \#pipe\# \#Fclose\#; this system call is used in the implementation of this routine.\end screen( capsensitive("creat")) NAME creat - create a new file SYNOPSIS #include <unistd.h> int creat(const char *path, unsigned int mode); DESCRIPTION This interface is made obsolete by \#open\#, since, creat(path, mode); is equivalent to open(path, O_WRONLY | O_CREAT | O_TRUNC, mode); which actually is the way creat is implemented. creat creates a new ordinary file or prepares to rewrite an existing file named by the pathname pointed to by path. If the file did not exist, it is given the mode 'mode', as modified by the process's mode mask (see \#umask\#). See \#stat\# for the construction of mode. If the file exists, its mode and owner remain unchanged, but it is truncated to 0 length. Otherwise, the file's owner ID is set to the effective user ID of the process, and upon successful completion, creat marks for update the st_atime, st_ctime, and st_mtime fields of the file (see \#stat\#) and the st_ctime and st_mtime fields of the parent directory. Upon successful completion, the file descriptor is returned and the file is open for writing, even if the access permis- sions of the file mode do not permit writing. The file pointer is set to the beginning of the file. The file descriptor is set to remain open across \#execve\# system calls. See \#fcntl\#. RETURN VALUES creat returns a non-negative descriptor that only permits writing on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#close\#, \#chmod\#, \#execve\#, \#fcntl\#, \#flock\#, \#open\#, \#write\#, \#umask\#\end screen( capsensitive("dup"), capsensitive("dup2")) NAME dup, dup2 - duplicate a file descriptor SYNOPSIS #include <unistd.h> int dup(int fd); int dup2(int fd1, int fd2); DESCRIPTION dup duplicates an existing file descriptor. The argument fd is a small non-negative integer index in the per-process descriptor table. The new descriptor returned by the call is the lowest numbered descriptor that is not currently in use by the process. With dup2, fd2 specifies the desired value of the new descriptor. If descriptor fd2 is already in use, it is first deallocted as if it were closed by \#close\#. The new descriptor has the following in common with the original: - It refers to the same object that the old descriptor referred to. - It uses the same seek pointer as the old descriptor (that is, both file descriptors share one seek pointer). - It has the same access mode (read, write or read/write) as the old descriptor. Thus if fd2 and fd1 are duplicate references to an open file, \#read\#, \#write\#, and \#lseek\# calls all move a single seek pointer into the file, and append mode is shared between the references. If a separate seek pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional \#open\# call. RETURN VALUES dup and dup2 return a new descriptor on success. On failure, they return -1 and set errno to indicate the error. SEE ALSO \#close\#, \#fcntl\#, \#lseek\#, \#open\#, \#pipe\#, \#read\#, \#write\# \#Fdup\#, \#Fforce\#, \#Fcntl\# - these system calls are used in the implementation of these routines.\end screen( capsensitive("exit"), capsensitive("_exit")) NAME exit, _exit - terminate process SYNOPSIS #include <stdlib.h> void exit(int status); #include <unistd.h> void _exit(int status); DESCRIPTION exit terminates the calling process in the following way: - All registered exit handlers are called (see \#atexit\#). - Standard input, standard output, and standard error output are flushed. - All other open file descriptors are closed - \#_exit\# is called with the argument passed to exit. Returning from main() with a value is identical to calling exit with the same value. _exit terminates the calling process without cleanup action: - If profiling is active, profiling will be ended and the results will be written out to file. - \#Pterm\# is called with the argument passed to _exit. SEE ALSO \#atexit\#, \#Pterm\#, \#wait\# NOTES The argument to exit is returned as the return code to the calling program. Zero should be returned on success, non- zero should be returned on failure or abnormal termination. The Operating System does many things on process termination not mentioned above. For instance, memory is freed, the parent process is signalled, file locks are released and so on.\end screen( capsensitive("fcntl")) NAME fcntl - file control SYNOPSIS #include <fcntl.h> int fcntl(int fildes, int cmd, ...); DESCRIPTION fcntl provides for control over open files. fildes is a file descriptor obtained from a \#creat\#, \#dup\#, \#fcntl\#, \#open\# or \#pipe\# call. Since the fcntl call is nothing but an interface to the \#Fcntl\# system call, the user is referred to the \#Fcntl\# page for an overview of available commands. SEE ALSO \#creat\#, \#dup\#, \#fcntl\#, \#open\#, \#pipe\# RETURN VALUES See \#Fcntl\# for a detailed description of return codes. In general, -1 is returned on failure; any other value indicates success; the meaning is dependent on the command executed. NOTES Under TOS, fcntl always returns -1. The available commands for \#Fcntl\# tend to increase all the time; the current list is likely to be out of date.\end screen( capsensitive("fork")) NAME fork - create a new process SYNOPSIS #include <unistd.h> int fork(void); DESCRIPTION fork creates a copy of the current process using \#Pfork\#. This call splits the program into two copies, both of which continue to run. The only difference between the two is the returned value. In one of these processes, the child, this is zero. In the other, the parent, it is non-zero; it is the process ID of the child (a positive number), or a negative error code if the call failed. SEE ALSO \link("exec")exec..\#, \#tfork\#, \#vfork\#, \#wait\# NOTES At the moment (MiNT 0.99 and earlier), \#Pfork\#, and consequently also fork, suspends the parent until the child has terminated or overlays itself. This has yet to be fixed, and may cause problems when porting UN*X programs. There are various intricate differences between the parent and the child process, like the effects of closing a file on which a lock has been obtained (the parent owns the locks). You are advised to check the man pages for \#Pfork\# and \#Pvfork\#, in addition to the kernel sources, if you really want to know.\end screen( capsensitive("getpagesize")) NAME getpagesize - get system default page size SYNOPSIS #include <unistd.h> int getpagesize(void); DESCRIPTION This function returns the default page size as used by the system. This may be of interest to programs that (partly) want to manage their memory allocation/deallocation. RETURN VALUES Under TOS or MiNT earlier than 0.9, 1024 is always returned. Using MiNT 0.9 or later, the default page size is returned. Currenly, pagesize is 8192 (the largest page size allowed by the MC68040 processor).\end screen( capsensitive("getpid"), capsensitive("getpgrp"), capsensitive("getppid")) NAME getpid, getprgp, getppid - get process, process group, and parent process IDs SYNOPSIS #include <unistd.h> int getpid(void); int getprgp(void); int getppid(void); DESCRIPTION getpid returns the process ID of the calling process. getpgrp returns the process group ID of the calling process. getppid returns the parent process ID of the calling process. SEE ALSO \#setpgrp\# \#Pgetpid\#, \#Pgetpgrp\#, \#Pgetppid\#; these system calls are used in the implementation of these routines. NOTES When MiNT is not active, the 16 most significant bits of the basepage of the process are returned for getpid; 0 is returned for getpgrp; the 16 most significant bits of the parents process' basepage are returned for getppid. It seems that the BSD UN*X version of getpgrp takes an argument.\end screen( capsensitive("getuid"), capsensitive("geteuid"), capsensitive("getgid"), capsensitive("getegid")) NAME getuid, geteuid, getgid, getegid - get real user, effective user, real group and effective group IDs SYNOPSIS #include <sys/types.h> #include <unistd.h> uid_t getuid(void); uit_t geteuid(void); gid_t getgid(void); gid_t getegid(void); DESCRIPTION getuid returns the real user ID of the calling process. geteuid returns the effective user ID of the calling process. getgid returns the real group ID of the calling process. getegid returns the effective group ID of the calling process. SEE ALSO \#setuid\#, \#setgid\# \#Pgetuid\#, \#Pgeteuid\#, \#Pgetgid\#, \#Pgetegid\#; these system calls are used in the implementation of these routines. NOTES On UN*X systems, these calls have the type unsigned short, which is equal to uid_t and gid_t. When MiNT is not active, these calls are pretty bogus. Pgeteuid and Pgetegid have only been available since MiNT 0.95\end screen( capsensitive("kill")) NAME kill - send a signal to a process or a group of processes SYNOPSIS #include <unistd.h> int kill(int pid, int sig); DESCRIPTION kill sends a signal to a process or a group of processes. The process of group of processes to which the signal is to be sent is specified by pid. The signal that is to be sent is specified by sig and is either on from the list given in \#signal\#, or 0. If sig is 0 (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of pid. The real user ID of the sending process must match the real user ID of the receiving process, unless the effective user ID of the sending process is super-user. If pid is greater than zero, sig will be sent to the process whose process ID is equal to pid. If pid is 0, sig will be sent to all processes whose process group ID is equal to the process group ID of the sender. If pid is negative, sig will be sent to all processes whose process group ID is equal to the absolute value of pid. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error SEE ALSO \#getpid\#, \#getpgrp\#, \#setprgp\#, \#signal\# \#Pkill\#; this system call is used in the implementation of this routine. NOTES Under UN*X, the real or effective user ID of the sending process must match the real or effective user ID of the receiving process, or the effective user ID of the sending process must be super-user. Under UN*X, the processes with a process ID of 0 and a process ID of 1 are treated specially.\end screen( capsensitive("link")) NAME link - link to a file SYNOPSIS #include <support.h> int link(const char *old, const char *new); DESCRIPTION old points to a path name naming an existing file. new points to a path name naming the new directory entry to be created. link creates a new hardlink (directory entry) for the existing file. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error. SEE ALSO \#readlink\#, \#symlink\#, \#unlink\# \#Flink\#; this system call is used in the implementation of this routine. NOTE link will only fuction properly if MiNT 0.9 or later is active and the file system supports hardlinks. MS-DOS (TOS) file systems do not support hardlinks.\end screen( capsensitive("lseek"), capsensitive("tell")) NAME lseek, tell - move read/write file pointer SYNOPSIS #include <unistd.h> long lseek(int fildes, long offset, int mode); long tell(int fd); DESCRIPTION fildes is a file descriptor returned from a \#creat\#, \#open\#, \#dup\#, or \#fcntl\# system call. lseek sets the file pointer associated with fildes as follows, according to value of the mode paramater: - SEEK_SET (0): the pointer is set to offset bytes - SEEK_CUR (1): the pointer is set to its current location plus offset - SEEK_END (2): the pointer is set to the size of the file plus offset If the seek would set the pointer beyond the end of the file, and the file is then written to, the file is extended with zeros. If the filesystem supports sparse files, this may not take much space on disc. The obsolete function tell(fd) is equivalent to: lseek(fd, 0L, SEEK_CUR). RETURN VALUES On success, the new position of the file pointer is returned. On failure, a negative number is returned, and errno is set. SEE ALSO \#creat\#, \#dup\#, \#fcntl\#, \#fseek\#, \#open\# \#Fseek\# - this system call is used in the implementation of this routine.\end screen( capsensitive("mkdir")) NAME mkdir - make a directory SYNOPSIS #include <unistd.h> int mkdir(const char *path, unsigned int mode); DESCRIPTION The routine mkdir creates a new directory with the name path. The mode of the new directory is initialized from the mode. The protection part of the mode argument is modified by the process's mode mask (see \#umask\#). The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to the process's effective group ID. The newly created directory is empty except for the entries '.' and '..'. RETURN VALUES 0 upon successfull completion. -1 on error; errno is set to indicate the error. SEE ALSO \#rmdir\# \#Dcreate\#; this system call is used in the implementation of this routine.\end screen( capsensitive("mknod")) NAME mknod - make a directory, or a special or ordinary file SYNOPSIS int mknod(const char *path, int mode, int dev); DESCRIPTION In the current version of MiNT and the mintlibs, mknod is bogus. It will always return -1, with errno set to EINVAL. SEE ALSO \#chmod\#, \#chown\#, \#creat\#, \#mkdir\#, \#umask\#\end screen( capsensitive("open")) NAME open - open or create a file for reading or writing SYNOPSIS #include <unistd.h> #include <fcntl.h> int open(const char *filename, int flags, ...); DESCRIPTION filename points to the pathname of a file. open opens the named file for reading and/or writing, as specified by the flags argument, and returns a descriptor for that file. The flags argument may indicate the file is to be created if it does not already exist (by specifying the O_CREAT flag). In this case an extra integer parameter pmode is used; the file is created with mode pmode as described in \#chmod\# and modified by the process' umask value (see \#umask\#). flags values are constructed by ORing flags from the following list (one and only one of the first three flags below must be used): - O_RDONLY Open for reading only. - O_WRONLY Open for writing only. - O_RDWR Open for reading and writing. - O_NDELAY Non-blocking I/O. - O_SYNC Synchronize after writes (not implemented). - O_APPEND If set, the seek pointer will be set to the end of the file prior to each write. - O_CREAT Create the file if it doesn't exist already. - O_TRUNC If the file exists and is a regular file, and the file is successfully opened using O_RDWR or O_WRONLY, its length is truncated to zero. - O_EXCL If O_EXCL and O_CREAT are set, open will fail if the file exists. The seek pointer used to mark the current position within the file is set to the beginning of the file. The new descriptor is set to remain open across \#execve\# system calls; see \#close\# and \#fcntl\#. RETURN VALUES open returns a non-negative file descriptor on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#chmod\#, \#close\#, \#creat\#, \#dup\#, \#fcntl\#, \#lseek\#, \#read\#, \#umask\#, \#write\#\end screen( capsensitive("pathconf")) NAME pathconf - query file system related limits and options SYNOPSIS #include <unistd.h> long pathconf(const char *path, int name); DESCRIPTION pathconf provides a method for the application to determine the current value of a configurable limit or option that is associated with the file-system containing the file or directory named in path. The following parameters to pathconf are supported: Name Meaning Note _PC_LAST max limit # for pathconf NOT POSIX _PC_IOPEN_MAX internal limit on open files NOT POSIX _PC_LINK_MAX max # of links POSIX _PC_PATH_MAX max len of a full pathname POSIX _PC_NAME_MAX max len of individual name POSIX _PC_PIPE_BUF bytes written atomically to fifo POSIX _PC_NO_TRUNC filename truncation POSIX RETURN VALUES pathconf returns the current variable value on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#sysconf\# \#Dpathconf\#; this system call is used in the implementation of this routine. NOTE It's a pity this routine does not conform to POSIX; but then, it's even more a pity that MiNT does not comply...\end screen( capsensitive("pause")) NAME pause - suspend process until signal SYNOPSIS ?? No header file yet. #include <signal.h>? void pause(void); DESCRIPTION pause suspends the calling process until it receives a signal. The signal must be one that is not currently set to be ignored by the calling process. If the signal causes termination of the calling process, pause will not return. SEE ALSO \#alarm\#, \#kill\#, \#signal\#, \#sigpause\#, \#wait\# \#Pause\#; this system call is used in the implementation of this routine. NOTE For vague reasons, pause returns an integer on System V.\end screen( capsensitive("pipe")) NAME pipe - create an interprocess communication channel SYNOPSIS #include <unistd.h> int pipe(int fd[2]); DESCRIPTION This function only works when MiNT is active. The pipe system call creates an I/O mechanism called a pipe and returns two file descriptors, fd[0] and fd[1]. fd[0] is opened for reading and fd[1] is opened for writing. When the pipe is written using the descriptor fd[1] up to 4096 bytes of data are buffered before the writing process is blocked. A read only file descriptor fd[0] accesses the data written to fd[1] on a FIFO (first-in-first-out) basis. The standard programming model is that after the pipe has been set up, two (or more) cooperating processes (created by subsequent \#fork\# calls) will pass data through the pipe using \#read\# and \#write\#. Read calls on an empty pipe (no buffered data) with only one end (all write file descriptors closed) returns an EOF (end of file). A SIGPIPE signal is generated if a write on a pipe with only one end is attempted. RETURN VALUES pipe returns: 0 on success. -1 on failure and sets errno to indicate the error. NOTES in MiNT, pipes are really the same as FIFOs. SEE ALSO \#fork\#, \#read\#, \#write\#, \#signal\# \#Fpipe\# - this system call has been used in the implementation of this routine.\end screen( capsensitive("read")) NAME read - read input SYNOPSIS #include <unistd.h> int read(int fd, void *buffer, unsigned int length); DESCRIPTION read attempts to read length bytes of data from the file referenced by the descriptor fd into the buffer pointed to by buffer. On objects capable of seeking, the read starts at a position given by the pointer associated with fd (see \#lseek\#). Upon return from read, the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current position. The value of the pointer associated with such an object is undefined. Upon successful completion, read returns the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file which has that many bytes left before the EOF (end of file), but in no other case. If nbytes is not zero and read returns 0, then EOF has been reached. If the descriptor or the object is marked for non-blocking I/O, and less data are available than are requested by the read, only the data that are available are returned, and the count indicates how many bytes of data were actually read. RETURN VALUES read returns the number of bytes actually read on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#dup\#, \#fcntl\#, \#ioctl\#, \#lseek\#, \#open\#, \#pipe\#\end screen( capsensitive("readlink")) NAME readlink - read value of a symbolic link SYNOPSIS #include <support.h> ?? int readlink(const char *path, char *buf, int bufsiz); // Should be like this int readlink(char *path, char *buf, int bufsiz); DESCRIPTION readlink places the contents of the symbolic link referred to by path in the buffer buf which has size bufsiz. The buffer must be large enough to hold the string and the terminating null. RETURN VALUES readlink returns the number of characters placed in the buffer, minus the terminating zero. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#lstat\#, \#symlink\# \#Freadlink\#; this system call is used in the implementation of this routine. NOTES On UN*X, the contents of the buffer is not null-terminated; the size of the buffer as passed to the readlink call is therefore off by one when compared to the mintlibs. It is unlikely that this would ever be a problem. MS-DOS (TOS) file-systems do not support symbolic links.\end screen( capsensitive("rmdir")) NAME rmdir - remove a directory SYNOPSIS #include <unistd.h> int rmdir(const char *path); DESCRIPTION rmdir removes the directory named by the path parameter. The directory must not have any entries other than "." and "..". RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error. SEE ALSO \#mkdir\# \#Ddelete\#; this system call is used in the implementation of this routine.\end screen( capsensitive("setuid"), capsensitive("setgid"), capsensitive("seteuid"), capsensitive("setegid"), capsensitive("setreuid"), capsensitive("setregid")) NAME setuid, setgid - set user and group IDs SYNOPSIS #include <unistd.h> int setuid(int uid); int setgid(int gid); DESCRIPTION setuid (setgid) is used to set the real user (group) ID and effective user (group) ID of the calling process. If the effective user ID of the calling process is super-user, the real user (group) ID and effective user (group) ID are set to uid (gid). If the effective user ID of the calling process is not super-user, but its real user (group) ID is equal to uid (gid), the effective user (group) ID is set to uid (gid). setuid (setgid) will fail if the real user (group) ID of the calling process is not equal to uid (gid) and its effective user ID is not super-user. RETURN VALUES 0 on success -1 on failure; errno is set to indicate the error. SEE ALSO \#getuid\#, \#getgid\#, \#geteuid\#, \#getegid\# \#Psetuid\#, \#Psetgid\#; these system calls are used in the implementation of these routines. NOTES The related functions seteuid, setegid, setreuid and setregid are also available in the MiNTlibs but really are the same. BUGS When MiNT is not active, these calls are pretty bogus. Security in MiNT is a joke; don't rely on these calls to actually protect you from anything, it's more for informational purposes.\end screen( capsensitive("signal")) NAME signal - software signal facilities SYNOPSIS #include <signal.h> __Sigfunc signal(int sig, __Sigfunc func); __Sigfunc is defined in <signal.h> in the following way: typedef void (*__Sigfunc) (int signum); DESCRIPTION Signals are only handled properly when MiNT is active. You are advised to read the entries for \#Psignal\#, \#Psigaction\#, \#Psigpause\# and \#Psigblock\# for the mechanism used. When MiNT is not active, signals are emulated under TOS. This fails to handle all types of signals properly. Signals for MiNT are explained in the document signal.doc, which comes with the MiNT distribution. A signal is generated by some abnormal event, initiated by a user at a terminal (quit, interrupt, stop), by a program error (bus error, etc.), by request of another program (kill), or when a process is stopped because it wishes to access its control terminal while in the background. Signals are optionally generated when a process resumes after being stopped, when the status of child processes changes, or when input is ready at the control terminal. Most signals cause termination of the receiving process if no action is taken; some signals instead cause the process receiving them to be stopped, or are simply discarded if the process has not requested otherwise. Except for the SIGKILL and SIGSTOP signals, the signal call allows signals either to be ignored or to interrupt to a specified location. For a list of signals and their default actions, see the file signal.doc. If func is SIG_DFL, the default action for signal sig is reinstated. If func is SIG_IGN the signal is subsequently ignored and pending instances of the signal are discarded. Otherwise, when the signal occurs further occurrences of the signal are automatically blocked and func is called. A return from the function unblocks the handled signal and continues the process at the point it was interrupted. After a \#fork\# or \#vfork\# the child inherits all signals. An \#execve\# resets all caught signals to the default action; ignored signals remain ignored. RETURN VALUES signal returns the previous action on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#execve\#, \#fork\#, \#getrlimit\#, \#kill\#, \#sigblock\#, \#sigsetmask\#, \#vfork\# NOTE As the document signal.doc shows, signals under MiNT work in a rather different way than the UN*X version. Also, the names and types of signals supported are different from the UN*X version.\end screen( capsensitive("stat"), capsensitive("lstat"), capsensitive("fstat")) NAME stat, lstat, fstat - get file status SYNOPSIS #include <sys/types.h> #include <sys/stat.h> int stat(const char *path, struct stat *buf); int lstat(const char *path, struct stat *buf); int fstat(int fd, struct stat *buf); DESCRIPTION stat obtains information about the file named by path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. lstat is like stat except in the cases where the named file is a symbolic link, in which case lstat returns information about the link, while stat returns information about the file the link references. fstat obtains the same information about an open file referenced by the the file descriptor, such as would be returned by an \#creat\#, \#open\#, \#dup\#, \#fcntl\# or \#pipe\# call. buf is a pointer to a stat structure into which information is placed concerning the file. The stat structure is defined in <sys/stat.h> and contains the following fields of interest: struct stat { u_short st_mode; /* file mode */ ino_t st_ino; /* the file serial number */ dev_t st_dev; /* device file resides on */ short st_rdev; /* the device identifier */ short st_nlink; /* number of hard links to the file */ uid_t st_uid; /* user ID of the owner */ gid_t st_gid; /* group ID of the owner */ off_t st_size; /* total size of the file, in bytes */ off_t st_blksize; /* preferred blocksize for system I/O */ off_t st_blocks; /* actual number of blocks allocated */ time_t st_mtime; /* file last modify time */ time_t st_atime; /* file last access time */ time_t st_ctime; /* file last status change time */ short st_attr; /* file attributes */ ... /* various fields reserved for MiNT */ }; The following masks are available in <sys/stat.h> to test the st_mode field in the stat structure: #define S_IFMT 0170000 /* type of file */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular file */ #define S_IFIFO 0120000 /* FIFO special */ #define S_IMEM 0140000 /* shared memory (?) */ #define S_IFLNK 0160000 /* symbolic link */ #define S_ISUID 04000 /* set-uid on execution */ #define S_ISGID 02000 /* set-gid on execution */ #define S_ISVTX 01000 /* save swapped text */ The following masks are available in <sys/stat.h> to test the st_attr field in the stat structure: #define S_IRUSR 0400 /* readable by user */ #define S_IWUSR 0200 /* writeable by user */ #define S_IXUSR 0100 /* executable by user */ #define S_IRGRP 0040 /* readable by group */ #define S_IWGRP 0020 /* writable by group */ #define S_IXGRP 0010 /* executable by group */ #define S_IROTH 0004 /* readable by others */ #define S_IWOTH 0002 /* writable by others */ #define S_IXOTH 0001 /* executable by others */ RETURN VALUES 0 on success. -1 on failure; errno is set to indicate the error. SEE ALSO \#chmod\#, \#chown\# for the use of file attributes. \#Fcntl\#, \#Fxattr\#: these systems calls are used in the implementation of the stat, lstat and fstat routines. NOTE When MiNT is not active, these calls are emulated under TOS. The TOS implemenation of fstat in particular is pretty bogus. You are advised to read the source code of stat.c if you want to make use of other than the most basic attributes under TOS emulation.\end screen( capsensitive("stime")) NAME stime - set time SYNOPSIS #include <unistd.h> int stime(long *tp); DESCRIPTION stime sets the system's idea of the time and date. tp points to the value of time as measured in seconds from 00:00:00 GMT January 1, 1970. SEE ALSO \#time\# \#Tsetdate\#, \#Tsettime\#; these system calls are used in the implementation of this routine. RETURN VALUES 0 on success. -1 on failure; errno is set to indicate the error. NOTE On UN*X, only the super-user may call this function. Under the current version of MiNT and using the current version of the mintlibs, any user is allowed to change the system time. Don't rely on this behavior, as it will be changed in the future.\end screen( capsensitive("symlink")) NAME symlink - make symbolic link to a file SYNOPSIS #include <support.h> int symlink(const char *old, const char *new); DESCRIPTION A symbolic link new is created to old (new is the name of the file created, old is the string used in creating the symbolic link). Either name may be an arbitrary path name; the files need not be on the same file system. The file that the symbolic link points to is used when an \#open\# operation is performed on the link. A \#stat\# on a symbolic link returns the linked-to file, while an \#lstat\# returns information about the link itself. This can lead to suprising results when a symbolic link is made to a directory. To avoid confusion in programs, the \#readlink\# call can be used to read the contents of a symbolic link. RETURN VALUES symlink returns: 0 on success -1 on failure; errno is set to indicate the error SEE ALSO \#link\#, \#readlink\#, \#unlink\# \#Fsymlink\#; this system call is used in the implementation of this routine. NOTES MS-DOS (TOS) file-systems do not support symbolic links. The file or directory linked to (old) need not exist.\end screen( capsensitive("tfork")) NAME tfork - start a new thread SYNOPSIS long tfork(int (*func)(long), long arg); DESCRIPTION tfork starts a new thread of execution running in the same address space. The new thread gets its own 4K stack, and starts at the address in func with arg on the stack, i.e. as though the main program had a call like (*func)(arg). The main program continues executing, with tfork returning the process ID of the child. If MiNT is not active, then the child runs to completion and the return value is the child's exit status; \#vfork\# relies on this behavior. SEE ALSO \link("exec")exec..\#, \#fork\#, \#vfork\#, \#wait\# NOTES Parent and child share the same memory; this could cause problems with some library calls, notably \#malloc\#.\end screen( capsensitive("time")) NAME time - get time SYNOPSIS #include <sys/types.h> #include <time.h> time_t time(time_t *tloc); DESCRIPTION time returns the value of time in seconds since 00:00:00 GMT, January 1, 1970. If tloc is non-zero, the return value is also stored in the location to which tloc points. SEE ALSO \#stime\# \#Tgetdate\#, \#Tgettime\#; this system calls are used in the implementation of this routine.\end screen( capsensitive("sysconf")) NAME sysconf - query system related limits, values, options SYNOPSIS #include <unistd.h> long sysconf(int name); DESCRIPTION The sysconf function provides a method for the application to determine the current value of a configurable system limit or option. The value does not change during the lifetime of the calling process. The following parameters to sysconf are supported: Name Meaning Note _SC_LAST max limit # for sysconf NOT POSIX _SC_MEMR_MAX memory regions per process NOT POSIX _SC_ARG_MAX max length of cmdln NOT quite POSIX _SC_OPEN_MAX max # of open files per process POSIX _SC_NGROUPS_MAX max # supp gids POSIX _SC_CHILD_MAX max # processes/user NOT quite POSIX RETURN VALUES sysconf returns the current variable value on success. On failure, it returns -1 and sets errno to indicate the error. SEE ALSO \#pathconf\# \#Sysconf\#; this system call is used in the implementation of this routine. NOTE It's a pity this routine does not conform to POSIX; but then, it's even more a pity that MiNT does not comply...\end screen( capsensitive("umask")) NAME umask - set file creation mode mask SYNOPSIS #include <unistd.h> #include <sys/stat.h> int umask(int mask); DESCRIPTION umask sets the process's file creation mask to mask and returns the previous value of the mask. The low-order 9 bits of mask are used whenever a file is created, clearing corresponding bits in the file access permissions (see \#stat\#). This clearing restricts the default access to a file. The mask is inherited by child processes. RETURN VALUES umask returns the previous value of the file creation mask. SEE ALSO \#chmod\#, \#open\# \#Pumask\# - this system call is used in the implementation of this routine.\end screen( capsensitive("unlink"), capsensitive("remove")) NAME unlink - remove directory entry SYNOPSIS #include <unistd.h> int unlink(char *path); #include <stdio.h> int remove(const char *path); DESCRIPTION unlink removes the directory entry named by the pathname pointed to by path. On file systems that allow hard links, the link count of the file referred to by that entry is decremented by one. If this entry was the last link to the file, the file is removed. If any process has the file open, and the file system supports removal of open files, the actual resource reclamation is delayed until the file is closed, even though the directory entry has disappeared. RETURN VALUES unlink returns: 0 on success. -1 on failure and sets errno to indicate the error. SEE ALSO \#close\#, \#link\#, \#rmdir\# NOTES Applications should use \#rmdir\# to remove directories. MS-DOS (TOS) filesystems do not support hardlinks. MS-DOS (TOS) filesystems only allow the removal of open files, to be deleted on closing, since MiNT 0.98. The file will still have a directory entry, though. The identical function remove is available for backwards compatibility. Its use is discouraged.\end screen( capsensitive("vfork")) NAME vfork - spawn new process in a memory efficient way SYNOPSIS #include <unistd.h> int vfork(void); DESCRIPTION vfork can be used to create new processes without fully copying the address space of the parent process, which is unnecessary in many cases. It is useful when the only purpose of \#fork\# would have been to create a new process just in order to do an \link("exec")exec..\# call. vfork differs from \#fork\# in that the child borrows the parent's memory and thread of control until a call to \link("exec")exec..\#, or an exit (either by a call to \#_exit\# or abnormally). The parent process is suspended while the child is using its resources. vfork returns zero to the child and (later) the process ID of the child to the parent. SEE ALSO \link("exec")exec..\#, \#fork\#, \#tfork\#, \#wait\# NOTES The child should never return from the procedure that called vfork, since that will mess up the stack frame for the parent on its return from vfork. The vfork call is not available in UN*X System V.3. It will disappear from SunOS in the future (in fact, it would have disappeared if it weren't for the program mentioned below). So, if you want to write portable code, \#fork\#, don't vfork. Changes the child makes to the parents' variables will have effect on the parent. Do not rely on this, since it is a disgusting habit. (Presumably, this is why the Berkeley C-Shell has been implemented this way.)\end screen( capsensitive("write")) NAME write - write on a file SYNOPSIS #include <unistd.h> int write(int fildes, const void *buf, unsigned nbyte); DESCRIPTION fildes is a file descriptor obtained from a \#creat\#, \#open\#, \#dup\#, \#fcntl\#, or \#pipe\# system call. write attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with fildes. When fildes indicates a device, writing always takes place at the current position. When fildes indicates a file, the actual writing of data proceeds from the position in the file indicated by the file pointer. Upon return from write, the file pointer is incremented by the number of bytes actually written. If the O_APPEND flag of the file status flags is set, the file pointer will be set to the end of the file prior to writing. RETURN VALUES Upon successful completion the number of bytes actually written is returned. Otherwise, -1 is returned and errno is set to indicate the error. NOTE The underlying call, \#Fwrite\#, takes a long nbyte parameter and returns a long result. This means that, when 16-bit integers are used, \#Fwrite\# can write over 64 Kb at a time while write cannot. SEE ALSO \#creat\#, \#dup\#, \#fcntl\#, \#lseek\#, \#open\#, \#pipe\# \#Fwrite\#; this system call is used in the implementation of this routine.\end